Skip to content

SEP 9 -- HTTP接口调用规范

Head

  • Author: larry
  • Status: draft
  • Type: Standards
  • Created: 2017-09-13

摘要

目前我们的服务器接口调用来自不同平台，在对HTTP报文的填充上，格式不太统一，包括UA和cookie等。

本文统一请求填充策略。

Cookie

正常的客户端，如果带有用户登录功能，则需要完整模拟浏览器对cookie的处理方式，也就是需要实现完整的session功能。

User-Agent

要求所有HTTP调用都必须传入UA头，包括浏览器页面、客户端、app、服务端调用。

UA格式

格式：product-1/version (comment) product-2/version (comment) product-3/version (comment) ....

各个产品按照重要性从高到底排序，注释部分是可选的。

例如系统已经添加了UA：Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2785.104，我们要添加采购APP的UA信息：GmPurchase/version

那么最终的结果是：Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2785.104 GmPurchase/version。也就是把我们自己的添加到最后

有些调用http lib的客户端软件，lib本身不会添加UA，那么把就只自己的放进去就行了。

客户端UA举例

  1. 浏览器页面：因为浏览器会默认添加UA，这里暂时可选。
  2. 称重客户端：GmWeighting/version
  3. 称重客户端pad：GmWeightingPad/version
  4. 司机APP：GmDriver/version
  5. 微信商城：GmShop/version
  6. station：GmStation/version
  7. app：GmShopApp/version
  8. 小程序:GmShopMp/version
  9. 采购APP：GmPurchase/version
  10. 服务端station服务：GmWebStation/version，因为服务端暂时没有version区分，这里就暂时填写1
  11. 服务端merchandise服务：GmServiceMerchandise/version，版本固定为1。

名字仅供参考，请自行命名。

自定义Head

  1. X-Guanmai-Client

    客户端识别。包含多个部分，空格分隔。

    客户端类型：内容直接使用UA中自身的部分。比如，GmWeighting/version

    客户端唯一识别：一个能唯一识别当前客户端的串，主要用于客户端软件，页面端不需要。比如：e7c2a53fbffa56743cd797563748cc40。生成方式见后文。

    多个部分合并后，X-Guanmai-Client: GmWeighting/version e7c2a53fbffa56743cd797563748cc40

  2. X-Guanmai-Request-Id：请求唯一ID

    请求唯一ID。目的是为了用这个id把一次请求的日志串联起来，便于分析和排查问题。

    生成方式：md5(uuid())，例如 X-Guanmai-Request-Id: e7c2a53fbffa56743cd797563748cc40

客户端唯一识别(ID)

给每个用户客户端分配一个唯一ID，用来区分不同的客户端。

客户端唯一ID可能的使用场景：

  • 在不需要用户使用不同子用户的情况下，控制用户同时可用客户端的数量。
  • 协助排查问题。
  • 分析统计客户端特征。

唯一ID的生成。

客户端每次启动的时候，检查本地是否保存了ID，如果没有，重新生成一个ID(uuid，去掉中间的'-'，或者做一个md5)。生成的ID保存在本地。